AWSサービス名のtypo削減用のtextlintルールとルール更新用のスクリプトを公開してみた(npmパッケージ)

AWSサービス名のtypo削減用のtextlintルールとルール更新用のスクリプトを公開してみた(npmパッケージ)

AWSのサービス名をよくtypoしてしまう。EC2って Amazon EC2だっけ、AWS EC2だっけ?と悩む方に力になれるようにtextlintのルールを公開してみました!
Clock Icon2023.03.08

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

こんにちは。AWS事業本部コンサルティング部に所属している今泉(@bun76235104)です。

みなさん技術ブログ書かれていますか?

弊社では多くの社員が毎日とんでもない数のブログアウトプットをしています。

その中でもやはりAWS系のサービスに関する記事は多いです。

AWS系のサービス・プロダクトは非常に多く、微妙にtypoしてしまうことがありませんか?

私はかなりあります。代表的な例だと以下のような形ですね。

OK: AWS Security Hub
OK: Security Hub
NG: Amazon Security Hub
NG: SecurityHub

今回はこのような間違いに気づけるようにtextlintルールを作成するとともに、ルール更新を自動化できるようにスクリプトを組んでみました。

npmモジュールとしても公開して、できるだけ使いやすいようにいたしました。

なお、この課題に同じようにtextlintのルールを作ってくれたエンジニアがすでに弊社にいます!(2019年!)

今回はこのイカしたエンジニアの活動を真似しつつ、最近使えるようになったAWSのJSONフィードなどを使って、できるだけルール更新を自動化できるように活動してみた次第です!

本人にも直接言おうと思いますが、この場でもビッグリスペクトを表明させていただきます!

先に結論(何ができるようにしたのか)

たとえば以下のようにtypoを含んだ文章を用意します。

これはテストです。

Security Hubは間にスペースが必要です。これはOKです。

SecurityHubの書き方ではスペースが足りないので指摘します。これはNGです。

AWSとAmazonの接頭辞も重要です。AWS Security HubはOKです。

Amazon Security Hubは誤っているため指摘します。これはNGです。

同様にAmazon EC2はOKです。

しかし、AWS EC2はNGです。

また、大文字とすべき箇所を小文字にするなどの表記揺れも指摘します。

たとえば、Security HUBはNGです。

当然Ec2もNGです。

これに対して以下のように作成したルールを適用してみます。

# インストール
npm i -g textlint textlint-rule-aws-service-name
# 実行
textlint --rule aws-service-name test.md

こんな感じで指摘してくれます。

 5:1  ✓ error  SecurityHub => Security Hub              aws-service-name
 9:1  ✓ error  Amazon Security Hub => AWS Security Hub  aws-service-name
13:5  ✓ error  AWS EC2 => Amazon EC2                    aws-service-name
17:6  ✓ error  Security HUB => Security Hub             aws-service-name
19:3  ✓ error  Ec2 => EC2                               aws-service-name
23:1  ✓ error  vPC => VPC                               aws-service-name

✖ 6 problems (6 errors, 0 warnings)
✓ 6 fixable problems.

また、VSCodeの拡張機能などを使うことで執筆中にリアルタイムで指摘を表示できます。

20230308_textlint_aws_vscode_image

使用方法・できること

以下のGitHubリポジトリのREADMEを参照してください。

現状できること・できないこともまとめています。ざっくりまとめると以下のような形です。

指摘可: Amazon Security Hub # AWS Security Hubと指摘してくれる
指摘可: Ec2 # EC2と大文字・小文字の揺れを指摘してくれる
指摘可: SecurityHub #スペースが必要なサービスにスペースがないことを指摘してくれる

指摘不可: Cloud Front #スペースが必要ないサービスにスペースがある 正: CloudFront
コントリビューターの活躍でver1.1.0より Cloud Frontのようなケースも検知する様になりました! 本当にありがたいです。

ルールファイルの更新について

ルールファイル(auto-create-regular-rules.yml)については、src配下のtsファイルで生成されるロジックを組んでいます。

更新の元ネタとなっているのは、こちらのJSONフィードです。

こちらから必要な情報だけを抜き取り・加工・ymlファイルを生成しています。

ルールファイルの作成ってどうしているの?と少し興味を持たれた方はbun913/textlint-rule-aws-service-nameをご参照ください。

今後の課題について

以下のようなパッションのままに、今回は2,3日くらいでルールを突貫で作ってみました。

  • 私が困っているから誰かも困っているだろう
  • 今年は初めてOSSにコントリビュートしたりしたけど、もう少しガッツリコードも書いてみたい
  • どうせなら初めてnpmパッケージも公開してみたいな

まさにBetter than Nothingという考えでスピードを重視したため、以下のような課題・展望があります。

  • 各種自動化
    • ルールファイルの変更を検知して、必要な時だけ自動でPullRequestを作成する
    • semantic-releaseの導入によるバージョン管理とnpmパッケージ更新の自動化
    • Dependabotの導入によるパッケージ更新
  • テストの充実
    • ルールファイルの検証テストを増やす(あまり書いていない)
    • ルールファイルを更新するためのコードのテストを増やす(ほとんど書いていない)
  • パッケージの軽量化・パフォーマンス検証
    • ざっとVSCodeで記事を書いている感じだとそこまで影響はないように思える
  • READMEの充実化

かなり雑なところもありますが、気になる点や改善点があれば以下リポジトリにてIssue・Pull Request作成をお待ちしています!

この記事・このルールが誰かの時間を1秒でも削減することになればうれしいです!

以上、今泉でした!

Share this article

facebook logohatena logotwitter logo

© Classmethod, Inc. All rights reserved.